home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / m2 / m2_part1.lha / modula / README < prev   
Text File  |  1994-07-30  |  14KB  |  354 lines
  1. ================================================================================
  2.  
  3.                         Amiga Turbo Modula-2 V1.0d (27/6/94)
  4.  
  5. Amiga Turbo Modula-2 (c) Copyright 1994 by Amritpal Mann, All Rights Reserved
  6.  
  7. ================================================================================
  8.  
  9.  
  10.     This is a freely distributable demonstration version of a (PIM4) Modula-2
  11.     development system. Amiga Turbo Modula-2 consists of:
  12.  
  13.         A compiler(M2C), a link utility(M2L), an error lister(M2E),
  14.         and a program builder(M2B).
  15.         Interface modules for V40 of the AmigaOS & corresponding linker library,
  16.         ANSI C standard library definitions as well as those from PIM.
  17.  
  18.     The compiler reads source code in a single pass which means fast
  19.     compilation. Internally however it performs several passes over each
  20.     procedures statement sequence in order to generate fast and compact code.
  21.     Typically, generated code is 25% smaller & 75% faster than the ($200)
  22.     commercial Amiga Modula-2 compiler used for the initial bootstraps.
  23.  
  24.     Turbo does not have its own linker, instead it requires a 'C' compiler
  25.     front-end to link generated code.
  26.     The unregistered freeware version of Matt Dillon's excellent C system,
  27.     DICE, has been included and contains 2 necessary programs, DCC & DLINK,
  28.     as well as vital startup code(c.o) and support libraries(c.lib,auto.lib,x.o)
  29.     Note that Turbo does NOT produce 'C' as intermediate output, it just uses
  30.     DCC to link and add startup code the machine code it generates.
  31.  
  32.     You do not need to know how to use DICE in order to generate M2 executables,
  33.     M2L calls DCC for you , all you need do is extract DICE (see below).
  34.     The reason for using DICE instead of say BLINK, are that DICE has excellent
  35.     support for generating residentable programs, also the standard C library
  36.     supplied with DICE becomes automatically available and finally
  37.     (for those of us who have slow(er) amigas) DLINK runs fast!
  38.  
  39.     The unregistered freeware version of DICE may be redistributed unmodified
  40.     & only in whole. This also applies to this demo version of Turbo Modula-2.
  41.  
  42.     The minimum required setup in order to use Turbo is 1MB of memory
  43.     and 1.2(V33) workbench & 2 disk drives. However I recommend
  44.     that you should have at least 1MB of available(free) memory and a hard disk.
  45.     Also M2B will not propagate ^C break detection to M2C & M2L unless you're
  46.     running under V36 or above. To use M2B you really need a real-time clock or
  47.     otherwise set the time at bootup or instead use M2C & M2L directly.
  48.  
  49.  
  50. Demo version limitations
  51. ========================
  52.  
  53.     In order to encourage you to purchase the full version of Turbo M2 the
  54.     compiler will refuse to compile modules (not programs) that translate to
  55.     more than 2K of machine code (that's about 250 lines of code) and contain
  56.     more than 4K of global variables. Only a small selection of library modules
  57.     are provided.
  58.  
  59.  
  60. Dice Extraction
  61. ===============
  62.  
  63.     The file dice/dice.lha contains the DICE system.In order to save your
  64.     hard disk space, the dice/M2EXTRACT script will extract the files that we
  65.     are interested in (as well as the DICE copyright messages etc):
  66.  
  67.         >cd dice
  68.         >execute M2EXTRACT
  69.  
  70.     You can of course extract the entire archive if you prefer.
  71.     If you already have DICE installed on your system, and are therefore not
  72.     extracting it again, you should make the apropriate modifications to the
  73.     INSTALL script...
  74.  
  75.  
  76. Directory Organisation
  77. ======================
  78.  
  79.     The two m2.lha parts should have unarchived a root directory named 'modula':
  80.  
  81.     INSTALL     Run this script each time you wish to try Turbo.
  82.                 The script assumes you have already extracted the files in
  83.                 dice/dice.lha (see above).
  84.  
  85.                 Type "execute INSTALL" to run the script.
  86.                 You must be in this directory for it to work.
  87.                 The script will make the necessary assignments and path
  88.                 additions.
  89.  
  90.                 The INSTALL script will assign 'MODULA:' to this directory.
  91.  
  92.     README      This file.
  93.  
  94.     EXTENSIONS  A description of some of the extra features added to the
  95.                 compiler (language extensions).
  96.  
  97.     DISCLAIMLER Please read this file before using any of the programs.
  98.  
  99.     M2OPTS      Default M2OPTS file (see below).
  100.  
  101.     examples/   Some example programs.
  102.  
  103.     src/        Source code for amiga interface, ANSI C and PIM definition
  104.                 modules.In order to save space, this demo contains only a small
  105.                 selection of modules.
  106.  
  107.     sym/        Symbol files for above definition modules.
  108.  
  109.     obj/        Compiled object modules, mainly from the implementation modules
  110.                 for the definition modules in src/. On startup these modules
  111.                 normally open the required amiga libraries (intuition etc).
  112.  
  113.     lib/        Contains linker libraries and support code.
  114.  
  115.     bin/        Executables for M2C, M2B, M2E & M2L.
  116.                 All these programs were developed using M2C, M2B, M2E & M2L :^)
  117.                 All can be made resident.
  118.                 They are only runable from the shell.
  119.  
  120.     dice/       DICE system.If you want to redistribute DICE then you must
  121.         include all the files in the dice/dice.lha archive.
  122.  
  123.  
  124. Filename extensions
  125. ===================
  126.  
  127.     *.err    Binary error file generated by M2C & M2B, used by M2E.
  128.     *.mod    Program/implementation module (ascii text).
  129.     *.def    Definition module (ascii text).
  130.     *.o      Standard Amiga object file, generated by M2C from a *.mod file.
  131.     *.sym    Symbol file generated by M2C from a *.def file.
  132.     *.lib    Linker Library. A concatenation of *.o files.
  133.     *.lnk    Linker object file list(ascii), written to the T: directory by M2L,
  134.              read by DCC.
  135.  
  136.  
  137. Error Lister (M2E)
  138. ==================
  139.  
  140.     If M2B or M2C encounter errors while processing a source file, then a
  141.     binary error file will be generated.
  142.     Use M2E to view the errors encoded in this file.
  143.  
  144.     usage: m2e modulename
  145.  
  146.  
  147. Program Builder (M2B)
  148. =====================
  149.  
  150.     M2B will take care of compilation and linking for you.It checks file
  151.     timestamps to see which files need to be (re)compiled/(re)linked.
  152.  
  153.     M2B is like MAKE, but instead of using a makefile it uses import lists.
  154.  
  155.     usage: m2b [-f][-v][-t] [compile/link options] filename [DCC options & args]
  156.  
  157.     -f: Force all time comparisons to fail(all modules will be (re)compiled).
  158.  
  159.     -v: Write out the name of each file as it is read.
  160.  
  161.     -t: Don't actually call M2C & M2L just print the commands that would have
  162.         been executed.
  163.  
  164.     example:
  165.  
  166.                                 /-------- -s passed to DCC
  167.       >m2b -v -p -b -q foo.mod -s
  168.                ^--^--^------------------ -p -b -q are compiler(M2C) options
  169.                                          -q is also an M2L option.
  170.  
  171.     Assuming that foo.o is older than foo.mod and foo.mod does not import
  172.     any other module then M2B will call M2C & M2L as
  173.  
  174.       m2c -p -b -q foo.mod
  175.       m2l -q foo.o -s  (but only if m2c did not fail)
  176.  
  177.     You may find the TOUCH program (in dice/bin/) useful when using M2B.
  178.  
  179.  
  180. Compiler (M2C)
  181. ==============
  182.  
  183.     usage: m2c [-D][-C][-b][-p][-w][-q][-l] {-Mdir} filename/modulename
  184.  
  185.     -D: Use large data model (default is small data model).
  186.         If your program declares more than 64K of global variables then you must
  187.         enable this option for each constituent module (except library
  188.         modules that were compiled small data & -l), otherwise linking will
  189.         fail. By allocating large data structures on the heap you can easily
  190.         avoid the need to use this option.
  191.  
  192.         Using the small data & code models will make your program more compact.
  193.         Compiling all modules small data will also allow a program to be
  194.         made fully resident.
  195.  
  196.     -C: Use large code model.
  197.         If a module compiles to about 32000 bytes or more, then you may need to
  198.         enable this option (depending on whether linking fails).
  199.         If a module compiles to more than 32767 bytes then you definitely need
  200.         to enable this option.
  201.  
  202.     -b: Enable array bounds checking.
  203.  
  204.     -p: Enable pointer checking.
  205.         The compiler will insert code to check that all pointer & VAR parameter
  206.         accesses are within a specific range.At the moment the bounds are
  207.         fixed to 1K..16M.If you're Amiga has valid memory outside this range
  208.         (and you're program may access it) then you cannot use this option.
  209.         Programmers who do not have a MMU, may find this option very useful.
  210.         Pointer checking should only be used during program development.
  211.  
  212.         Depending on programming style (access procedures or open structures),
  213.         pointer checking may or may not massively increase the size of a program
  214.         It does not slow down a program by as much as you may expect.
  215.  
  216.     -w: Disable compiler warnings.
  217.  
  218.     -q: Be quiet.
  219.  
  220.     -l: (equivalent to the DICE option -S)
  221.         Name BSS(global variable space) section libbss instead of just 'bss'.
  222.         Use this option to compile re-usable modules that do not have much BSS.
  223.         This will enable you to use small code library modules with (large code)
  224.         program modules that declare a lot of BSS.This option avoids the need to
  225.         have two different versions (one small & one large) of said modules.
  226.  
  227.  
  228.     -M: Add dir to the symbol file directory search path.
  229.         If a dir/sym/ subdirectory exists, it will be added instead.
  230.  
  231.     It is possible to set/clear some of these options inside a source text
  232.     by using comments, however this method is not described here.
  233.  
  234.     If a Modula-2 run-time error occurs (illegal case index, halt called,
  235.     array/pointer checking etc) the run time support code (in M2.lib) will
  236.     display a requester with the first 4 letters of the module name and (full)
  237.     line number of where the error occurred.
  238.  
  239.     ¥ou can use dice/dobj to view the machine code generated by the compiler.
  240.  
  241.   One pass compilation
  242.   --------------------
  243.  
  244.     The compiler operates in a single pass, this means that you must declare
  245.     variables & procedures before you use them.The compiler provides the FORWARD
  246.     keyword in order to allow early declarations for procedures that are
  247.     implemented later.
  248.  
  249.     PROCEDURE f( ) ; FORWARD ; (* implementation must be in the same scope *)
  250.  
  251.     PROCEDURE g( ) ;
  252.     BEGIN f( ) ;
  253.     END g ;
  254.  
  255.     PROCEDURE f( ) ; (* alternatively we could nest f( ) inside g( ) *)
  256.     BEGIN g( )
  257.     END f ;
  258.  
  259.     If a procedure is declared in a definition module then a forward declaration
  260.     in the corresponding implementation module is never required.
  261.  
  262.   Type sizes & extremal values
  263.   ----------------------------
  264.  
  265.             size (bytes)                range
  266.             ============                =====
  267.  
  268.     SHORTCARD   1                     0 .. 255
  269.     CARDINAL    2                    0  .. 65535
  270.  
  271.     SHORTINT    1                   -128 .. 127
  272.     INTEGER     2                 -32768 .. 32767
  273.     LONGINT     4                -(2^31) .. (2^31)-1
  274.  
  275.     SHORTREAL   4                   Motorola FFP
  276.     REAL        4               IEEE single precision
  277.     LONGREAL    8               IEEE double precision
  278.  
  279.     There is also a LONGCARD datatype which is declared as a
  280.     LONGINT[0..MAX(LONGINT)].
  281.  
  282.  
  283. Linker frontend (M2L)
  284. =====================
  285.  
  286.     M2L calls DCC (which in turn calls DLINK) to link the object modules
  287.     generated by the compiler into an executable file. M2L is itself normally
  288.     called by M2B (M2B->M2L->DCC->DLINK).
  289.  
  290.     Usage: m2l [-q] {-Mdir} module[.o] [DCC options & args]
  291.  
  292.     -q    : Quiet, don't print the path of each file as it is read.
  293.  
  294.     -Mdir : Add directory dir to the object file search path.
  295.             If a dir/obj/ subdirectory exists, it will be added instead.
  296.  
  297.     module: Program (root) module name.
  298.             This object module must be in a local directory
  299.  
  300.     Anything on the command line that follows the module name is passed to DCC.
  301.  
  302.     example: m2l -q foo -s -r
  303.                          ^--^-- passed to dcc.
  304.  
  305.     This will invoke DCC:
  306.  
  307.     dcc -LMODULA:lib @t:foo.lnk -s -r -ofoo
  308.  
  309.     Where t:foo.lnk (intermediate file generated by M2L) will contain:
  310.  
  311.     m2_main.o
  312.     foo.o
  313.     m2.lib
  314.  
  315.     m2_main.o m2.lib are normally in directory MODULA:lib
  316.  
  317.  
  318. M2OPTS
  319. ======
  320.  
  321.     An optional ascii text file named M2OPTS in the MODULA: directory can
  322.     specify M2C and M2L command line options.
  323.  
  324.     M2L filters M2OPTS looking for -q & -M's ignoring all other options.
  325.     Options in M2OPTS are scanned before command line options.
  326.  
  327.     An M2OPTS text in your source directory will override the one in MODULA: .
  328.  
  329.  
  330. Ordering the full version
  331. =========================
  332.  
  333.     If you would like the full version of Amiga Turbo Modula-2, which can only
  334.     be ordered from me:
  335.  
  336.         Mr A S Mann
  337.         1 Blossom Way,
  338.         West Drayton,
  339.         Middlesex,
  340.         England (UK),
  341.         UB7-9HF.
  342.  
  343.     At the very reasonable price of 25 pounds sterling or 40 US dollars.
  344.     This is inclusive of postage, disks etc and at least 1 update.
  345.     I can only accept cheques from a UK bank, Royal Mail postal order(crossed),
  346.     Eurocheck, or an International money order that is redeemable in the UK.
  347.  
  348.     UK mainland users can try sending cash, but this is not recomended.
  349.     International orders should never include cash.
  350.  
  351.     Please print your name & address clearly.
  352.  
  353.     -- Thankyou for trying Turbo, the best Amiga Modula-2 compiler available!
  354.